docs: bootstrap chisel docs #186
Conversation
This commit adds a skeleton of the documentation based on docs starter pack: https://canonical-starter-pack.readthedocs-hosted.com/latest/. Note that the docs themselves are not updated. Only necessary files and hacks are introduced in this commit.
Read reuse/substitutions.yaml if it exists into myst_substitutions to reuse content with simple markdown. Additionally, delete reuse/links.txt since we are not using reStructuredText. This commit also updates a few misc settings in conf.py.
Update the site landing page (/) at docs/index.md with a summary of Chisel and proper links to different sections. This commit also creates a few placeholder files and directories for later use, e.g. reference/, how-to/index.md etc.
Mostly copied from the Rockcraft docs: https://documentation.ubuntu.com/rockcraft/en/stable/explanation/chisel/#package-slices
Additionally add placeholder CLI commands reference pages.
This commit adds reference pages for all Chisel subcommands.
This reverts commit b69bbea.
|
FYI @yhontyk |
There was a problem hiding this comment.
This is amazing Cristovao and Rafid! I think this is exactly what we were looking for in the first complete version of the documentation. It is comprehensive and detailed, it is correct from a technical point of view, and yet it does not feel unnecessarily verbose. LGTM!
| ```{note} | ||
| This field is only applicable to paths with no wildcards, and its value | ||
| must also be an absolute path with no wildcards. | ||
| ``` |
There was a problem hiding this comment.
Maybe this should be an attribute in the table above so that it is uniform for all attributes. Thoughts?
There was a problem hiding this comment.
To be pragmatic, my opinion is:
- we'd eventually want to auto generate this page from the code itself. In that case, such attribute would probably be a bit trickier to generate from the code (?)
- there are more fields without this note, than with it, so in the sake of avoiding empty space within the tables, I'd just keep it as it
| system. | ||
|
|
||
| It currently accepts only one value - `mutate`. If specified, the path will only | ||
| be available until the {{mutation_scripts}} execute, and is removed afterwards. |
There was a problem hiding this comment.
It is a bit more nuanced. Basically the file is removed as soon as no other slices need it. For example, one slice may need it only until mutation but the other may use until: none meaning it will need it in the final filesystem. Because it is needed, the file is not removed.
There was a problem hiding this comment.
I'll try to rephrase it. Please check the coming update on canonical/chisel-docs#4
|
@letFunny your comments have been addressed in canonical/chisel-docs@71c2694 FYI @yhontyk this is being moved to canonical/chisel-docs#4 |
Needs #185
This PR creates the first version of the Chisel docs.
More doc pages and functionality are planned for coming PRs, such as:
cutstages (e.g. the process of fetching, parsing and validating an Ubuntu release)preview: https://canonical-chisel--186.com.readthedocs.build/en/186/